////////////////////////////////////////////////////////////////////////////////
// Copyright 2010 Michael Schmalle - Teoti Graphix, LLC
// 
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// 
// http://www.apache.org/licenses/LICENSE-2.0 
// 
// Unless required by applicable law or agreed to in writing, software 
// distributed under the License is distributed on an "AS IS" BASIS, 
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and 
// limitations under the License
// 
// Author: Michael Schmalle, Principal Architect
// mschmalle at teotigraphix dot com
////////////////////////////////////////////////////////////////////////////////

package org.teotigraphix.swizplugin.api
{

import org.swizframework.core.ISwiz;

/**
 * The <strong>IPlugin</strong> interface defines a client capable of holding 
 * <code>IPluginExtensionPoint</code> and <code>IPluginExtension</code>
 * instances.
 * 
 * <p>An <strong>IPlugin</strong> is required to have a <code>uid</code> unique 
 * identifier at runtime to differentiate itself from the rest of the 
 * <strong>IPlugin</strong>'s in an application.</p>
 * 
 * <p>It is recomended to use a reverse domain name in the <code>uid</code> as 
 * done with naming actionscript packages.</p>
 * 
 * <pre>
 * &lt;!-- src/com/acme/plugins/MyPlugin.mxml --&gt;
 * 
 * &lt;swizplugin:Plugin
 * 	xmlns:swizplugin="http://swizplugin.teotigraphix.org"
 * 		uid="{PLUGIN_ID}"&gt;
 *    
 * 		... in &lt;fx:Script&gt;
 * 		public static const PLUGIN_ID:String = "com.acme.ui";
 * 		...
 * 
 * 		&lt;swizplugin:points&gt;
 * 			... IPluginExtensionPoint declarations
 * 		&lt;/swizplugin:points&gt;
 * 
 * 		...
 * 
 * 		&lt;swizplugin:extensions&gt;
 * 			... IPluginExtension declarations
 * 		&lt;/swizplugin:extensions&gt;
 * 
 * &lt;/swizplugin:Plugin&gt;
 * </pre>
 * 
 * @author Michael Schmalle
 * @copyright Teoti Graphix, LLC
 * @productversion 1.0
 */
public interface IPlugin
{
	//--------------------------------------------------------------------------
	//
	//  Properties
	//
	//--------------------------------------------------------------------------
	
	//----------------------------------
	//  uid
	//----------------------------------
	
	/**
	 * The unique identifier of the plugin instance.
	 * 
	 * <p><strong>Note:</strong> This property is required, if it is not defined
	 * when this plugin is added as a contributor to the extension registry, an
	 * Error will be thrown.</p>
	 * 
	 * @see org.teotigraphix.swizplugin.registry.IExtensionRegistry#addContributor()
	 */
	function get uid():String;
	
	/**
	 * @private
	 */
	function set uid(value:String):void;
	
	//----------------------------------
	//  points
	//----------------------------------
	
	[ArrayElementType("org.teotigraphix.swizplugin.api.IPluginExtensionPoint")]
	
	/**
	 * The plugin's implemented <code>IPluginExtensionPoint</code> points.
	 */
	function get points():Array;
	
	/**
	 * @private
	 */
	function set points(value:Array):void;
	
	//----------------------------------
	//  extentions
	//----------------------------------
	
	[ArrayElementType("org.teotigraphix.swizplugin.api.IPluginExtension")]
	
	/**
	 * The plugin's implemented <code>IPluginExtension</code> extensions.
	 */
	function get extentions():Array;
	
	/**
	 * @private
	 */
	function set extentions(value:Array):void;
}
}